Skip to content

API Documentation

The NotePost API is extremely simple to use. Requests can be sent via GET or POST, and responses are sent in JSON.

Request Structure

API URLs are typically of the form http(s)://notepost-url/api/<action>/?args.

Clients can authenticate to the API by using HTTP Basic Authentication or by including username and password arguments.

Response Structure

Responses to well-formed requests will have a status field containing the string OK or ERROR.
If status is ERROR, there will also be a field named msg containing a human-readable localized error message suitable for display to the user.
If status is OK, there may or may not be additional fields sent, depending on the action.

If the request is not well-formed (missing required arguments, invalid credentials, or invalid action), the API will send a 4xx HTTP code and some plain text, such as "400 Bad Request", "403 Unauthorized", or "404 Action not defined".

Note JSON Format

    {
        "noteid": 10,
        "color": "673AB7",
        "content": "#Note\ncontent",
        "html": "<h1>Note</h1><p>content</p>",
        "title": "Note",
        "modified": 1547271000,
        "favorite": false,
        "owner": {
            "uid": 1,
            "username": "someone",
            "name": "Some One"
        }
    }

Actions

Action Additional Arguments Description
ping None Used to check if the server is online and responding. Responds with {"status":"OK"}.
getnotes None Returns all the notes that are readable with the sent credentials, as an array named notes. See note format above.
getnote id Get one note by its ID.
savenote text, id (optional), color (optional), modified (optional), favorite (optional), archived (optional) Update a note and return the updated note in note.
If id is not set, creates a new note. Returns the saved note as JSON, along with a msg containing a translated "Note saved" message.
If color is set to six hexadecimal digits, the note's background color will be set.
If modified is set to a string parsable by PHP strtotime, the note's last modified date will be set accordingly, otherwise the current date and time will be used.
If favorite is set to either 0 (no) or 1 (yes), the note's favorite/starred status will be updated.
archived is ignored for now, but will operate the same as favorite in the future as a non-destructive form of deletion.
deletenote id Delete a note by its ID. This is not reversible.
favoritenote id, favorite (optional) If favorite is not set, the favorite status of the note will be toggled. If favorite is set to either 0 (no) or 1 (yes), the note will be set as favorited or not.
tolist id Convert a note to a list by prepending a checkbox (- [ ]) to each line of text. Returns the updated note as note.
togglelist id, text Toggle the checked/crossed out state of the given line of text in the given note.

Nextcloud Notes API

A subset of NotePost's functionality can also be accessed via a server implementation the Nextcloud Notes API. Use it via https://notepost-url/lib/nextcloudnotes.php, or if your webserver is configured correctly (see the .htaccess file in the NotePost root folder), at https://notepost-url/index.php/apps/notes/api/v0.2. See the linked Nextcloud documentation for usage information.